# this code exists because ...
I'm seeing code which only exists because the problem was misunderstood or maybe unclear at the outset. But, determining that this is why it exists in the current form (or at all) requires me to read all of it, decipher some convoluted conditionals (some of which are redundant), and speculate about whether some questionable parts are bugs or happy accidents which are required to function properly.
Namely, this module (which will forever remain nameless because it no longer exists) where the best fix was file deletion. It didn't even have a synopsis. It was a brute-force solution the wrong problem, with a few solutions in the middle to problems which would not exist if the code didn't exist.
Of course, all of our code problems go away if we have no code. That much should be obvious to even the most inept. But we have a non-code problem to be solved with code -- that's where we usually start. I like to use the Feynman method:
1. Write down the problem.
2. Think very hard.
3. Write down the solution.
Step #1 is "the most important comment". Step #3 is the code. I'll never be privy to what happened in your head during step #2, but if I can see the comment and the code, I can see whether your code solves the problem. If you solved the wrong problem, I can probably save a lot of time reading the code.
